﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Asynchronous commands</title>
  <keywords>
    <keyword translate="true">Asynchronous</keyword>
    <keyword translate="true">AsynchronousCommand</keyword>
    <keyword translate="true">CancelCommand</keyword>
    <keyword translate="true">Commands</keyword>
    <keyword translate="true">MVVM</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Asynchronous commands</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Commands in MVVM are a very precious good. Actually, MVVM can&apos;t exist without them because they allow a developer to bind to a method (that&apos;s actually all an </text><text styleclass="Normal" style="font-style:italic;" translate="true">ICommand</text><text styleclass="Normal" translate="true"> implementation is). However, sometimes it is required to create asynchronous commands. Starting with Catel 3.1, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_AsynchronousCommand" styleclass="Normal" translate="true">AsynchronousCommand</link><text styleclass="Normal" translate="true"> is introduced.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">With the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_AsynchronousCommand" styleclass="Normal" translate="true">AsynchronousCommand</link><text styleclass="Normal" translate="true">, it is possible to create a command that executes a method in the background without blocking the UI thread. It is possible to report progress to the UI thread.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Creating the command</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_AsynchronousCommand" styleclass="Normal" translate="true">AsynchronousCommand</link><text styleclass="Normal" translate="true"> can be used the same as the the regular </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Command" styleclass="Normal" translate="true">Command</link><text styleclass="Normal" translate="true"> class. The command must be constructed like this:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">CancelableAsyncCommand</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">AsynchronousCommand(OnCancelableAsyncCommand,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">()</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">!CancelableAsyncCommand.IsExecuting);</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The second parameter is the </text><text styleclass="Normal" style="font-style:italic;" translate="true">CanExecute</text><text styleclass="Normal" style="font-style:normal;" translate="true"> delegate, and this example does not allow multiple executions of the same command at the same time.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Running the command</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Running the command is the same as the regular </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Command" styleclass="Normal" translate="true">Command</link><text styleclass="Normal" translate="true"> class. The view can simply bind to the command like the code below:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#8000ff;" translate="true">Button</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">Command=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#0080ff;" translate="true">&quot;{Binding CancelableAsyncCommand}&quot;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">Content=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#0080ff;" translate="true">&quot;Execute Command&quot;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">/&gt;</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Canceling the command</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Last but not least, the cool thing about the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_AsynchronousCommand" styleclass="Normal" translate="true">AsynchronousCommand</link><text styleclass="Normal" translate="true"> is that it can complete in two ways. It either completes the method by itself, or it is canceled from the outside. To cancel a running command, two steps must be accomplished:</text></para>
    <list id="1" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal"><text styleclass="Normal" translate="true">Bind to the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="P_Catel_MVVM_AsynchronousCommand`2_CancelCommand" styleclass="Normal" style="font-style:normal;" translate="true">CancelCommand</link><text styleclass="Normal" style="font-style:normal;" translate="true"> property of the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_AsynchronousCommand" styleclass="Normal" translate="true">AsynchronousCommand</link><text styleclass="Normal" translate="true">:</text></li>
    </list>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#8000ff;" translate="true">Button</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">Command=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#0080ff;" translate="true">&quot;{Binding CancelableAsyncCommand.CancelCommand}&quot;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">Content=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#0080ff;" translate="true">&quot;Cancel Command&quot;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">/&gt;</text></para>
    <list id="1" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal"><text styleclass="Normal" translate="true">Make sure the </text><text styleclass="Normal" style="font-style:italic;" translate="true">execute</text><text styleclass="Normal" translate="true"> action checks the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="P_Catel_MVVM_AsynchronousCommand`2_ShouldCancel" styleclass="Normal" translate="true">ShouldCancel</link><text styleclass="Normal" translate="true"> property like in the example below:</text></li>
    </list>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">private</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">void</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">OnCancelableAsyncCommand()</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">for</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">1;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&lt;=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">100;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i++)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">if</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(CancelableAsyncCommand.ShouldCancel)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> &#160; &#160; &#160; &#160; &#160; &#160;// If we should cancel, break out of the loop</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">break</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Thread.Sleep(100);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Note that this example looks stupid and you should not use Thread.Sleep, but this is just for the sake of simplicity and the example</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Reporting progress</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">During the execution of a command, it is possible to report progress back to the main thread. This can done by using the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_AsynchronousCommand`2_ReportProgress_1_62c6d5e6" styleclass="Normal" style="font-style:normal;" translate="true">ReportProgress</link><text styleclass="Normal" translate="true"> method. All code inside the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_AsynchronousCommand`2_ReportProgress_1_62c6d5e6" styleclass="Normal" style="font-style:normal;" translate="true">ReportProgress</link><text styleclass="Normal" style="font-style:normal;" translate="true"> will be executed in the UI thread:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">private</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">void</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">OnCancelableAsyncCommand()</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">for</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">1;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&lt;=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">100;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i++)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">if</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(CancelableAsyncCommand.ShouldCancel)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#000000;" translate="true">// If we should cancel, break out of the loop</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">break</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i1</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">i;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">CancelableAsyncCommand.ReportProgress(()</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Messages.Add(i1.ToString(CultureInfo.InvariantCulture)));</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Thread.Sleep(100);</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">}</text></para>
  </body>
</topic>
